/*
Welcome to KeyWasFull's script set! Remember, to make it so my scripts work, you will want to make sure that keyWasFull is part of the load_scripts flag in your map pack settings.

the following script flags are available:

randomize (bool)
useable on: skills
this flag allows the skill to summon multiple units near it and enables the  following supporting flags for the skill:
randomize_unit_type (string): this is the type of unit that the function will summon. Spaces will be treated as spaces, so unless the unit name itself has underscores, do not use them.
randomize_unit_team (int, optional): the number of the team to which the summoned units will be affiliated. If this flag is not specified, it defaults to the team of the unit who used the skill.
randomize_num_of_units (int): The number of units to be summoned. Dice and ranges, such as 7d4 and 5r16, can also be used here.
randomize_radius_horizontal (int, optional): the summoner of the randomized units is the center of a rectangular area. This value represents the width of the rectangle in which the summoned units will be created. If not specified, the default is 5. Note that the radius values do not support randomized values.
randomize_radius_vertical (int, optional): the height of the rectangle in which summoned units will be placed. If not specified, the default is 5.
randomize_display_success (bool optional): if this flag is enabled, a debug message about what was placed will be displayed after the randomization is performed. Otherwise, no message will be displayed. You can use Craig's success_message flag if you want to display your own message.

warnings:
Make sure your rectangle is large enough and empty enough to hold the summoned units. If there is no more space to fit a unit that you wish to summon or all the squares in the rectangle are ocupied and uninhabitable, the game will hang or flag a script error, either of which will be embarrassing if your users realize it first. It is a lot safer to summon a small number of units, and increase the number. Run the skill at least 10 times to get a good amount of trials.
Make sure that if you are allowed to use a randomized value in your flag, the syntax is correct, otherwise it will flag a script error.
Make sure that the rectangle does not go off the edge of the screen. For example if you have a unit on the far left of the map, some of the units will probably not show up because they were trying to be summoned outside the map. Move the summoner to a more centralized location or decrease the size of the rectangle if you are summoning near the map edge. If you want to calculate if your summoned units have a chance of being summoned off the edge of the map, the amount of squares which the unit will be summoned, either vertically or horizontally, is radius_horizontal/2 rounded up to the nearest whole number. For example if you have a summoner at 14 4, and your rectangle's vertical radius is greater than 8, units will have a chance of being summoned off the map.


random_stats (bool)
useable on: units an structures
this flag enables the randomization of the stats of each unit or structure of this type that is created, as well as enabling the usage of the following supporting flags:
random_stats_max (string, optional): allows you to randomize the maximum value of the points that you list. The format is pointName|value,pointName|value. Ranges and dice rolls should be used for the value, otherwise the stats will not actually be random. If the random_stats_current flag does not mention this point and the original current value of the point is greater than the randomized maximum value, the point's value will be decreased to the new maximum.
example: random_stats_max health|350r450,actions|6d2
random_stats_current (string, optional): this flag allows you to set the starting value of the points in your list. The listed points can be different from the max point list. The syntax is exactly the same as the syntax for random_stats_max.
random_stats_full_points (bool, optional): if this flag is set, points that were modified in the random_points_max flag will be checked to see if their current values need to be restored to the max, and will be restored if they are lower than the max. If this flag is skipped, they will maintain the values they used to have as defined by the point_max flag in your unit file.

note: make sure you define the points that the unit has, even if it is to give them a health-max of 50000, only to modify it later. Otherwise the game will give errors about points that don't exist.

equip_apply_effects (string)
applies to: items
Applies the effect to the unit who equips this item. When the item is unequipped, the effect is removed also.

equip_remove_effects (string)
applies to: items
Causes effects to be removed from the unit when the item is equipped. These effects are not reapplied when the item is unequipped. This is most useful if you have created a temporary effect for a unit, and a permanent version of the same effect that you want only available when the item is equipped. You could then prevent the two effects from stacking by removing the temporary effect when the equipment is put on.

equip_message; unequip_message (string)
applies to: items
speaks a message when the user equips or unequips this item. This supports the placeholders {0} for the unit who equips the item, and {1} for the name of the item.
example: equip_message {0} puts on the {1}.
unequip_message {0} shrugs off the {1}.

equip_max_mod (string)
applies to: items
Modifies the unit's point maximums. the format is point|value,point|value. Only solid positive or negative integers are supported for the values. By default this will also modify the current amount of the point by the same amount, so a unit that gained 15 maximum health from a piece of equipment would also regain 15 current health. The max and current points are subtracted when the equipment is removed. If you want to prevent the current values of the points from being affected, use equip_lock_current_points.
supporting flag: equip_lock_current_points (bool): prevents the actual point values from being modified when the user equips an item that has an equip_max_mod flag on it.
Note: I decided to support only locking points when an item is both equipped and unequipped, because it doesn't make sense to lock points on just one or the other. Otherwise a unit could repeatedly wear and unwear the same piece of equipment to get healed of all damage, or restore other points.

equip_sound and unequip_sound (string)
applies to: items
plays the sound when the item is equipped/unequipped. Supports random selection of consecutively numbered sounds.

team_change_start_turn (int)
applies to: effects
allows a unit to have an effect that changes its team at the start of the turn. This is useful for skills that hide units from enemy attack, because you can switch them to a team at the end of your turn so that the enemy doesn't attack him then switch him back for the duration the effect lasts.
supporting flag: team_change_end_turn (int): switches the unit to a different team when his  turn on the new team ends. 
Warning: Make sure team_change_start_turn flag is less than team_change_end_turn flag so that the team's turn is changed during the same round. Otherwise the unit will have to wait a second round for his team to be changed.

effects_duration_mod (string)
applies to: skills
Changes the duration of effects on the targeted unit or tile, if it has them and they are not permanent. The syntax is effectname|mod, effectname|mod. Effect names should exactly match file names, including spaces (do not use underscores to replace spaces like what you usually do). Note that if the mod you set for an effect is negative and the effect's duration is shorter than the mod, the effect will be completely removed.
Example: effects_duration_mod lesser disease|-3,greater disease|-1

death_splash_range (int)
applies to: units
This flag is required for inflicting damage or applying effects to nearby units when this unit dies.
associated flags:
death_splash_inflict (string): when this unit dies, it deals the associated damage. The format is point|damage|damage_type,point|damage|damage_type.
example: death_splash_inflict health|25|fire,health|40|ice
death_splash_effects: Applies the effects to the units in the splash range.

start_tile (ints)
applies to: maps
moves the review cursor to this tile when the map is loaded, assuming square 1,1 is in the top left corner of the map. This flag also moves the cursor when the map is loaded in the editor.
example: start_tile 5 14

points_max_end_turn_mod (string)
applies to: units, effects
modifies the point maximums and the current amount of the point at the end of the turn so that they stay in proportion. For example if a unit had 8 of 10 hp, and you modified the hp point max by 10, the unit would then have 16 of 20 hp. This can be used to simulate units getting stronger or weaker as time passes. This flag supports negative modifications, limits on increases and chances of the point being increased. Read the examples below to learn the usage.
examples:
points_max_end_turn_mod health|25r50: increases the unit's max health by between 25 and 50 each round.
points_max_end_turn_mod health|45|75%: The unit has a 75% of  increasing the unit's maximum and current health by 45 each round.
points_max_end_turn_mod actions|2|85%|15: 85% chance to increase the unit's maximum/current actions by 2 each round. Actions will stop increasing once they equal or exceed 15.
points_max_end_turn_mod health|-25r70|100%|100: decreases the unit's maximum and current health by between 25 and 70 each round until it has equal to or less than 100 health.
Note: If you want to supply a limit, you must supply a percent also.

permanent (bool)
applies to: effects
Makes an effect permanent. Permanent effects are denoted by a negative amount of rounds remaining on them. Permanent effects can be removed, but their durations cannot be modded using effects_duration_mod.

teleport_to (string)
applies to: terrain
Causes a non-flying unit to teleport to the given tile (assuming that y coordinates do not increase as you move up) when it moves onto the terrain with this flag. If you want multiple teleportation tiles that teleport you to different locations, you will have to create a separate terrain for each one. You can use the friendly_name to make the teleportation tiles look the same. Note that if you move a unit on to the teleportation terrain, it will still say that the unit moved onto the tile; just ignore the message.
optional flag:
teleport_flying (bool): causes all units, whether flying or not, to be teleported.

view_equipment (boolean)
applies to: map
enables the shift-q hotkey to view equipped items on a unit. Due to scripting limitations, only the name of the item is read out, and not the slot in which it is equipped.
*/